@dotcom-reliability-kit/log-error

@dotcom-reliability-kit/log-error

A method to consistently log error object with optional request information. This module is part of FT.com Reliability Kit.

• Usage
  • logHandledError
  • logRecoverableError
  • logUnhandledError
  • Configuration options
    • options.error
    • options.includeHeaders
    • options.logger
    • options.logUserErrorsAsWarnings
    • options.request
• Migrating
• Contributing
• License

Usage

Install @dotcom-reliability-kit/log-error as a dependency:

npm install --save @dotcom-reliability-kit/log-error

Include in your code:

import {logRecoverableError} from '@dotcom-reliability-kit/log-error';
// or
const {logRecoverableError} = require('@dotcom-reliability-kit/log-error');

logHandledError

The logHandledError function can be used to log errors consistently to the console and Splunk via Reliability Kit logger. This method is used to indicate that the error being logged has been correctly handled and the application can continue to run.

logHandledError({
    error: new Error('Something went wrong')
});

This will automatically serialize error objects and log them. The information logged looks like this:

{
    event: 'HANDLED_ERROR',
    message: 'Error: something went wrong',

    error: {
        code: 'EXAMPLE_CODE',
        message: 'Something went wrong'
        // etc. (see `@dotcom-reliability-kit/serialize-error` linked above
        // for information about the logged properties
    },

    app: {
        commit: '137da65185397a7d699ed54c3052d10d83e82137',
        name: 'example-app',
        nodeVersion: '18.17.0',
        region: 'EU',
        releaseDate: '2022-07-25T01:37:00Z'
    }
}

logRecoverableError

The logRecoverableError function can be used to log errors consistently to the console and Splunk via Reliability Kit logger. This method is used to indicate that the error being logged was completely recoverable, with no error page sent to a user.

logRecoverableError({
    error: new Error('Something went wrong')
});

The information logged looks like this:

{
    event: 'RECOVERABLE_ERROR',
    message: 'Error: something went wrong',

    error: {
        code: 'EXAMPLE_CODE',
        message: 'Something went wrong'
        // etc. (see `@dotcom-reliability-kit/serialize-error` linked above
        // for information about the logged properties
    },

    app: {
        commit: '137da65185397a7d699ed54c3052d10d83e82137',
        name: 'example-app',
        nodeVersion: '18.17.0',
        region: 'EU',
        releaseDate: '2022-07-25T01:37:00Z'
    }
}

logUnhandledError

The logUnhandledError function can be used to log errors consistently to the console and Splunk via Reliability Kit logger. This method is used to indicate that the error being logged was not recoverable and resulted in an application crashing.

logUnhandledError({
    error: new Error('Something went wrong')
});

The information logged looks like this:

{
    event: 'UNHANDLED_ERROR',
    message: 'Error: something went wrong',

    error: {
        code: 'EXAMPLE_CODE',
        message: 'Something went wrong'
        // etc. (see `@dotcom-reliability-kit/serialize-error` linked above
        // for information about the logged properties
    },

    app: {
        commit: '137da65185397a7d699ed54c3052d10d83e82137',
        name: 'example-app',
        nodeVersion: '18.17.0',
        region: 'EU',
        releaseDate: '2022-07-25T01:37:00Z'
    }
}

Configuration options

Config options can be passed into all of the provided logging functions as an object, with the keys below:

logRecoverableError({
    // Options go here
});

options.error

The error object to log. This is the only required option.

logRecoverableError({
    error: new Error('Something went wrong')
});

options.includeHeaders

An array of request headers to include in the serialized request object (if one is provided with options.request). This must be an Array of Strings, with each string being a header name. It's important that you do not include headers which include personally-identifiable-information, API keys, or other privileged information. This option gets passed directly into dotcom-reliability-kit/serialize-request which has further documentation.

This option defaults to:

[
    'accept',
    'accept-encoding',
    'accept-language',
    'content-type',
    'referer',
    'user-agent'
]

Example of usage:

logRecoverableError({
    // ...other required options
    includeHeaders: [
        'accept',
        'content-length',
        'content-type',
        'user-agent'
    ]
});

The default set of headers is also available to use, so that you don't need to repeat them if you want to add new included headers. You'll need to import @dotcom-reliability-kit/serialize-request, then these headers are available:

const { DEFAULT_INCLUDED_HEADERS } = require('@dotcom-reliability-kit/serialize-request');

logRecoverableError({
    // ...other required options
    includeHeaders: [
        ...DEFAULT_INCLUDED_HEADERS,
        'my-custom-header'
    ]
});

[!NOTE]
There's no need to include the x-request-id header in this array, as this is automatically included as request.id in the logs.

options.logger

A logger object which implements two methods: error and warn. It may implement other methods but they're not used. The methods have a very permissive signature:

type LogMethod = (...logData: any) => any;

Though it's best if they can accept a single object and output results as JSON.

This option defaults to Reliability Kit logger.

options.logUserErrorsAsWarnings

[!NOTE]
This option is only available in the logHandledError function.

A boolean indicating whether to log user errors (those with a 400–499 status property) with a level of warn rather than error. This helps to reduce the amount of error-level logs that you need to focus on.

This option defaults to false.

options.request

A request object (e.g. an instance of Express.Request or an object with method and url properties) to include alongside the error in the log. This will be automatically serialized with @dotcom-reliability-kit/serialize-request.

app.get('/example', (request, response, next) => {
    logRecoverableError({
        // ...other required options
        request: request
    });
    next();
});

When this option is defined, the logged data looks includes request data:

{
    event: 'RECOVERABLE_ERROR',
    message: 'Error: something went wrong',

    error: {
        code: 'EXAMPLE_CODE',
        message: 'Something went wrong'
        // etc. (see `@dotcom-reliability-kit/serialize-error` linked above
        // for information about the logged properties
    },

    request: {
        id: 'abc123',
        method: 'GET',
        url: '/'
        // etc. (see `dotcom-reliability-kit/serialize-request` linked above
        // for information about the logged properties)
    },

    app: {
        commit: '137da65185397a7d699ed54c3052d10d83e82137',
        name: 'example-app',
        nodeVersion: '18.17.0',
        region: 'EU',
        releaseDate: '2022-07-25T01:37:00Z'
    }
}

Migrating

Consult the Migration Guide if you're trying to migrate to a later major version of this package.

Contributing

See the central contributing guide for Reliability Kit.

License

Licensed under the MIT license.
Copyright © 2022, The Financial Times Ltd.